---
title: Organizations
icon: Users
---

Organizations allow users to create and manage teams, workspaces, or companies within your application. This feature provides a complete multi-tenant system with role-based access control, member management, and invitation workflows.

## Overview

The organization system in Better Auth UI provides:

- **Multi-organization Support**: Users can create and belong to multiple organizations
- **Role-Based Access Control**: Built-in roles (owner, admin, member) plus custom roles
- **Member Management**: Invite, remove, and manage organization members
- **Organization Switching**: Seamlessly switch between organizations and personal accounts
- **Permission System**: Fine-grained permissions for different actions
- **Invitation Workflow**: Email-based invitation system with expiration

## Enabling Organizations

To enable organizations, configure the `organization` prop in your `AuthUIProvider`:

```tsx title="providers.tsx"
<AuthUIProvider
  authClient={authClient}
  organization={{
    logo: {
      upload: async (file) => {
        // Your upload logic
        return uploadedUrl
      },
      size: 256,
      extension: "png"
    },
    customRoles: [
      { role: "developer", label: "Developer" },
      { role: "viewer", label: "Viewer" }
    ]
  }}
>
  {children}
</AuthUIProvider>
```

## Key Components

### OrganizationSwitcher
The main component for switching between organizations and personal accounts:

```tsx
import { OrganizationSwitcher } from '@daveyplate/better-auth-ui'

<OrganizationSwitcher />
```

### SettingsCards with Organization View
The settings component automatically shows organization options when enabled:

```tsx
import { SettingsCards } from '@daveyplate/better-auth-ui'

// Shows organization settings when view="ORGANIZATION"
<SettingsCards view="ORGANIZATION" />

// Shows organization members when view="MEMBERS"
<SettingsCards view="MEMBERS" />

// Shows all organizations when view="ORGANIZATIONS"
<SettingsCards view="ORGANIZATIONS" />
```

### Organization-Specific Components

- `<OrganizationSettingsCards />` - Organization settings management
- `<OrganizationMembersCard />` - Member management
- `<OrganizationInvitationsCard />` - Pending invitations
- `<OrganizationsCard />` - List all user's organizations
- `<AcceptInvitationCard />` - Accept invitation flow

## Built-in Roles

Organizations come with three built-in roles:

1. **Owner**
   - Full control over the organization
   - Can delete the organization
   - Can transfer ownership
   - Can manage all members and settings

2. **Admin**
   - Can manage organization settings
   - Can invite and remove members
   - Can update member roles (except owner)
   - Cannot delete the organization

3. **Member**
   - Basic access to the organization
   - Cannot manage settings or members
   - Can leave the organization

## Custom Roles

You can define additional roles for your specific needs:

```tsx
organization={{
  customRoles: [
    { role: "developer", label: "Developer" },
    { role: "viewer", label: "View Only" },
    { role: "billing", label: "Billing Administrator" }
  ]
}}
```

## Organization Hooks

Access organization data programmatically:

```tsx
import { useContext } from 'react'
import { AuthUIContext } from '@daveyplate/better-auth-ui'

function MyComponent() {
  const { hooks } = useContext(AuthUIContext)
  
  // Get active organization
  const { data: activeOrg } = hooks.useActiveOrganization()
  
  // List all organizations
  const { data: organizations } = hooks.useListOrganizations()
  
  // Check permissions
  const { data: hasPermission } = hooks.useHasPermission({
    permissions: {
      organization: ["update"],
      member: ["create", "delete"]
    }
  })
  
  return (
    <div>
      Current org: {activeOrg?.name}
    </div>
  )
}
```

## Invitation Flow

1. **Send Invitation**: Admin/Owner sends invitation via email
2. **Email Delivery**: Recipient receives invitation email
3. **Accept/Reject**: User clicks link to accept or reject
4. **Join Organization**: User becomes a member with assigned role

## Best Practices

1. **Logo Configuration**: Set up logo upload for better branding
2. **Role Planning**: Define custom roles based on your needs
3. **Permission Checks**: Always check permissions before sensitive actions
4. **Invitation Expiry**: Set reasonable expiration times
5. **Member Limits**: Consider implementing member limits for plans

## Security Considerations

- **Session Freshness**: Some actions require fresh authentication
- **Permission Validation**: All actions are permission-checked server-side
- **Invitation Security**: Invitations include secure tokens
- **Data Isolation**: Organization data is properly isolated
- **Audit Trail**: Consider logging organization actions 